Utils

General

Many tools and utilities are present in spinal.lib but some are already present in the SpinalHDL Core.

Syntax	Return	Description
`widthOf(x : BitVector)`	Int	Return the width of a Bits/UInt/SInt signal
`log2Up(x : BigInt)`	Int	Return the number of bits needed to represent `x` states
`isPow2(x : BigInt)`	Boolean	Return true if `x` is a power of two
`roundUp(that : BigInt, by : BigInt)`	BigInt	Return the first `by` multiply from `that` (included)
`Cat(x : Data*)`	Bits	Concatenate all arguments, the first in MSB, the last in LSB

Cloning hardware datatypes

You can clone a given hardware data type by using the cloneOf(x) function. It will return a new instance of the same Scala type and parameters.

For example:

def plusOne(value : UInt) : UInt = {
  // Will recreate a UInt with the same width than ``value``
  val temp = cloneOf(value)
  temp := value + 1
  return temp
}

// treePlusOne will become a 8 bits value
val treePlusOne = plusOne(U(3, 8 bits))

You can get more information about how hardware data types are managed on the Hardware types page.

Note

If you use the cloneOf function on a Bundle, this Bundle should be a case class or should override the clone function internally.

Passing a datatype as construction parameter

Many pieces of reusable hardware need to be parameterized by some data type. For example if you want to define a FIFO or a shift register, you need a parameter to specify which kind of payload you want for the component.

There are two similar ways to do this.

The old way

A good example of the old way to do this is in this definition of a ShiftRegister component:

case class ShiftRegister[T <: Data](dataType: T, depth: Int) extends Component {
  val io = new Bundle {
    val input  = in (cloneOf(dataType))
    val output = out(cloneOf(dataType))
  }
  // ...
}

And here is how you can instantiate the component:

val shiftReg = ShiftRegister(Bits(32 bits), depth = 8)

As you can see, the raw hardware type is directly passed as a construction parameter. Then each time you want to create an new instance of that kind of hardware data type, you need to use the cloneOf(...) function. Doing things this way is not super safe as it’s easy to forget to use cloneOf.

The safe way

An example of the safe way to pass a data type parameter is as follows:

case class ShiftRegister[T <: Data](dataType: HardType[T], depth: Int) extends Component {
  val io = new Bundle {
    val input  = in (dataType())
    val output = out(dataType())
  }
  // ...
}

And here is how you instantiate the component (exactly the same as before):

val shiftReg = ShiftRegister(Bits(32 bits), depth = 8)

Notice how the example above uses a HardType wrapper around the raw data type T, which is a “blueprint” definition of a hardware data type. This way of doing things is easier to use than the “old way”, because to create a new instance of the hardware data type you only need to call the apply function of that HardType (or in other words, just add parentheses after the parameter).

Additionally, this mechanism is completely transparent from the point of view of the user, as a hardware data type can be implicitly converted into a HardType.

Frequency and time

SpinalHDL has a dedicated syntax to define frequency and time values:

val frequency = 100 MHz
val timeoutLimit = 3 ms
val period = 100 us

val periodCycles = frequency * period
val timeoutCycles = frequency * timeoutLimit

For time definitions you can use following postfixes to get a TimeNumber:

fs, ps, ns, us, ms, sec, mn, hr

For time definitions you can use following postfixes to get a HertzNumber:

Hz, KHz, MHz, GHz, THz

TimeNumber and HertzNumber are based on the PhysicalNumber class which use scala BigDecimal to store numbers.

Binary prefix

SpinalHDL allows the definition of integer numbers using binary prefix notation according to IEC.

val memSize = 512 MiB
val dpRamSize = 4 KiB

The following binary prefix notations are available:

Binary Prefix	Value
Byte, Bytes	1
KiB	1024 == 1 << 10
MiB	1024² == 1 << 20
GiB	1024³ == 1 << 30
TiB	1024⁴ == 1 << 40
PiB	1024⁵ == 1 << 50
EiB	1024⁶ == 1 << 60
ZiB	1024⁷ == 1 << 70
YiB	1024⁸ == 1 << 80